home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_kdelibs.idb / usr / freeware / kde / include / ktopwidget.h.z / ktopwidget.h
Encoding:
C/C++ Source or Header  |  1999-01-26  |  14.0 KB  |  446 lines
  1. #ifndef _KWIDGET_H
  2. #define _KWIDGET_H
  3.  
  4.  
  5.  
  6.  
  7. #include <stdlib.h>
  8. #include <qwidget.h>
  9. #include <qlist.h>
  10. #include <ktoolbar.h>
  11. #include <kmenubar.h>
  12. #include <kstatusbar.h>
  13. #include <kconfig.h>
  14.  
  15.  // $Id: ktopwidget.h,v 1.31 1998/06/20 10:56:58 radej Exp $
  16.  // $Log: ktopwidget.h,v $
  17.  // Revision 1.31  1998/06/20 10:56:58  radej
  18.  // sven: mispelled something...
  19.  //
  20.  // Revision 1.30  1998/06/19 16:39:15  radej
  21.  // sven: Docs.
  22.  //
  23.  // Revision 1.29  1998/06/19 14:16:36  radej
  24.  // sven: Docs.
  25.  //
  26.  // Revision 1.28  1998/06/12 19:39:18  ettrich
  27.  // Matthias: Something I noticed with KLyX
  28.  //
  29.  //
  30.  //     /** Deletes all KTMainWindows. This is a good thing to call before
  31.  //       * an applications wants to exit via kapp->quit(). Rationale: The
  32.  //       * destructors of main windows may want to delete other widgets
  33.  //       * as well. Now, if an application calls kapp->quit() then Qt
  34.  //       * will destroy all widgets in a somewhat random order which may
  35.  //       * result in double-free'ed memory (=segfault). Since not every
  36.  //       * program checks for QApplication::closingDown() before deleting
  37.  //       * a widget, calling KTMainWindow::deleteAll() before is a good
  38.  //       * and proper solution.
  39.  //      */
  40.  //   static void deleteAll();
  41.  //
  42.  //     /** Deletes all KTopLevelWidgets. This is a good thing to call before
  43.  //       * an applications wants to exit via kapp->quit(). Rationale: The
  44.  //       * destructors of main windows may want to delete other widgets
  45.  //       * as well. Now, if an application calls kapp->quit() then Qt
  46.  //       * will destroy all widgets in a somewhat random order which may
  47.  //       * result in double-free'ed memory (=segfault). Since not every
  48.  //       * program checks for QApplication::closingDown() before deleting
  49.  //       * a widget, calling KTopLevelWidgets::deleteAll() before is a good
  50.  //       * and proper solution.
  51.  //       */
  52.  //       static void deleteAll();
  53.  //
  54.  // Revision 1.27  1998/04/07 20:14:05  radej
  55.  // Made memberList public, so YOU can use it
  56.  // instead your window lists.
  57.  //
  58.  // Revision 1.26  1998/04/05 18:19:48  radej
  59.  // Reverted to old interface (before Matthias' changes) + Docs
  60.  //
  61.  // Revision 1.25  1998/04/04 11:43:14  radej
  62.  // Minor docs update.
  63.  //
  64.  
  65.  /**
  66.   * A Widget that provides toolbars, a status line and a frame.
  67.   * It should be used as a toplevel (parent-less) widget and
  68.   * manages the geometry for all its children, including your
  69.   * main widget.
  70.   *
  71.   * Normally, you will inherit from KTopLevelWidget (further: KTW).
  72.   * Then you must construct (or use some existing) widget that will be
  73.   * your main view. You set that main view only once.
  74.   *
  75.   * You can add as many toolbar(s) as you like. There can be only one Menubar
  76.   * and only one StatusBar.
  77.   *
  78.   * YOU MUST DELETE TOOLBARS AND MENUBAR ON EXIT (in destructor);
  79.   * If you have multiple windows then create window on the heap and
  80.   * delete it in your reimplementation of closeEvent.
  81.   *
  82.   * KTopLevelWidget maintaines the layout and resizing of all elements
  83.   * (toolbars, statusbar, main widget, etc).  KTW now handles fixed-size
  84.   * and Y-fixed main views properly. Just set fixed size or
  85.   * your main view. You can change it runtime, the changes will take effect
  86.   * on next updateRects call. Do not set fixed size on window! You may set
  87.   * minimum or maximum size on window, but only if main view is freely
  88.   * resizable. Minimum width can also be set if main view is Y-fixed.
  89.   *
  90.   * KTopLevelWidget will set icon, mini icon and caption,  which it gets
  91.   * from KApplication. It provides full session management, and will save
  92.   * its position geometry and positions of toolbar(s) and menubar on
  93.   * logout. If you want to save aditional data, overload saveProperties and
  94.   * (to read them again on next login) readProperties. To warn user
  95.   * that application has unsaved data on logout use setUnsavedData.
  96.   *
  97.   * There is also a macro RESTORE which can restore all your windows
  98.   * on next login.
  99.   *
  100.   * There is also an easyer to use top level widget, KTMainWindow by
  101.   * Matthiass Ettrich.
  102.   *
  103.   * KTopLevelWidget might be replaced/extended in the future to
  104.   * KMainWindow which will be a child of QMainWindow. Anyway,
  105.   * the current interface (as well as KTMainWindow) will be
  106.   * supported for compatibility reasons. It is also probable that
  107.   * both widgets will merge.
  108.   *
  109.   * @see KTMainWindow
  110.   * @see KApplication
  111.   * @short KDE top level widget
  112.   * @author Stephan Kulow (coolo@kde.org) Maintained by Sven Radej (sven@lisa.exp.univie.ac.at)
  113.   */
  114. class KTopLevelWidget : public QWidget {
  115.     Q_OBJECT
  116.  
  117.      friend class KToolBar;
  118.  
  119. public:
  120.     /**
  121.      * Constructor.
  122.      */
  123.     KTopLevelWidget( const char *name = 0L );
  124.     /**
  125.      * Destructor. You must delete all *Bars either here or in
  126.      * @ref #closeEvent.
  127.      */
  128.     ~KTopLevelWidget();
  129.  
  130.     /** Deletes all KTopLevelWidgets. This is a good thing to call before
  131.       * an applications wants to exit via kapp->quit(). Rationale: The
  132.       * destructors of main windows may want to delete other widgets
  133.       * as well. Now, if an application calls kapp->quit() then Qt
  134.       * will destroy all widgets in a somewhat random order which may
  135.       * result in double-free'ed memory (=segfault). Since not every
  136.       * program checks for QApplication::closingDown() before deleting
  137.       * a widget, calling KTopLevelWidgets::deleteAll() before is a good
  138.       * and proper solution.  
  139.       */
  140.       static void deleteAll();
  141.  
  142.     /**
  143.      * Add toolbar. If index is -1 toolbar will be appended on end
  144.      * of list of toolbars. Returns ID of toolbar. (for use in @ref #toolBar )
  145.      */
  146.     int addToolBar( KToolBar *toolbar, int index = -1 );
  147.  
  148.     /**
  149.      * Set the main client widget.
  150.      * This is the main widget for your application; it's geometry
  151.      * will be automatically managed by KTopLevelWidget to fit the
  152.      * client area, constrained by the positions of the menu, toolbars
  153.      * and status bar. It can be fixed-width or Y-fixed.
  154.      *
  155.      * Only one client widget can be handled at a time; multiple calls
  156.      * of setView will cause only the last widget to be added to be
  157.      * properly handled.
  158.      *
  159.      * The widget must have been created with this instance of
  160.      * KTopLevelWidget as its parent.
  161.      */
  162.     void setView( QWidget *view, bool show_frame = TRUE );
  163.  
  164.     /**
  165.      * Set the menuBar. There can be only one menubar. You can get
  166.      * pointer to menubar with function @ref #menuBar .
  167.       */
  168.     void setMenu( KMenuBar *menu );
  169.  
  170.     /**
  171.      * Set the statusbar. There can be only one statusbar. You can get
  172.      * pointer to status with function @ref #statusBar .
  173.      */
  174.     void setStatusBar( KStatusBar *statusbar );
  175.  
  176.     
  177.     /**
  178.      *Enable or disable the status bar.
  179.      */
  180.     void enableStatusBar( KStatusBar::BarStatus stat = KStatusBar::Toggle );
  181.  
  182.     /**
  183.      * Enable or disable the toolbar with the ID specified.
  184.      * If no ID is specified, the default ID is 0.
  185.      */
  186.     void enableToolBar( KToolBar::BarStatus stat = KToolBar::Toggle,
  187.                         int ID = 0 );
  188.  
  189.     /**
  190.      * Set the width of the view frame.
  191.      * If you request a frame around your view with @ref #setView (...,TRUE),
  192.      * you can use this function to set the border width of the frame.
  193.      * The default is 1 pixel. You should call this function before
  194.      * @ref #setView().
  195.      */
  196.     void setFrameBorderWidth( int );
  197.  
  198.     /**
  199.      * Returns a pointer to the toolbar with the specified ID. 
  200.      */
  201.     KToolBar *toolBar( int ID = 0 );
  202.  
  203.     /**
  204.      * Returns a pointer to the menu bar. 
  205.      */
  206.     KMenuBar *menuBar();
  207.  
  208.     /**
  209.      * Returns a pointer to the status bar.
  210.      */
  211.     KStatusBar *statusBar();
  212.  
  213.     /**
  214.      * Shows toplevel widget. Reimplemented from QWidget, and calls
  215.      * @ref #updateRects . Therefore, it is enough just to show KTW.
  216.      */
  217.     virtual void show ();
  218.  
  219.     /**
  220.      * Distance from top of window to top of main view,
  221.      * Computed in @ref #updateRects. Changing of this variable
  222.      * has no effect. Avoid using it, it might be removed in future.
  223.      */
  224.     int view_top;
  225.  
  226.     /**
  227.      * Distance from top of window to bottom of main view.
  228.      * Computed in @ref #updateRects. Changing of this variable
  229.      * has no effect. Avoid using it, it might be removed in future.
  230.      */
  231.     int view_bottom;
  232.  
  233.     /**
  234.      * Distance from left edge of window to left border of main view.
  235.      * Computed in @ref #updateRects. Changing of this variable
  236.      * has no effect. Avoid using it, it might be removed in future.
  237.      */
  238.     int view_left;
  239.  
  240.     /**
  241.      * Distance from left edge of window to right edge of main view.
  242.      * Computed in @ref #updateRects. Changing of this variable
  243.      * has no effect. Avoid using it, it might be removed in future.
  244.      */
  245.     int view_right;
  246.  
  247.  
  248.  
  249.   /**
  250.    * Try to restore the toplevel widget as defined number (1..X)
  251.    * If the session did not contain that high number, the configuration
  252.    * is not changed and False returned.
  253.    * 
  254.    * That means clients could simply do the following:
  255.    * <pre>
  256.    * if (kapp->isRestored()){
  257.    *   int n = 1;
  258.    *   while (KTopLevelWidget::canBeRestored(n)){
  259.    *     (new childTLW)->restore(n);
  260.    *     n++;
  261.    *   }
  262.    * } else {
  263.    * // create default application as usual
  264.    * }
  265.    * </pre>
  266.    * Note that "show()" is called implicit in restore.
  267.    *
  268.    * With this you can easily restore all toplevel windows of your
  269.    * application.  
  270.    *
  271.    * If your application uses different kinds of toplevel
  272.    * windows, then you can use KTopLevelWidget::classNameOfToplevel(n)
  273.    * to determine the exact type before calling the childTLW
  274.    * constructor in the example from above.  
  275.    * 
  276.    * If your client has only one kind of toplevel widgets (which should
  277.    * be pretty usual) then you should use the RESTORE-macro:
  278.    *
  279.    * <pre>
  280.    * if (kapp->isRestored())
  281.    *   RESTORE(childTLW)
  282.    * else {
  283.    * // create default application as usual
  284.    * }
  285.    * </pre>
  286.    *
  287.    * The macro expands to the term above but is easier to use and
  288.    * less code to write.
  289.    *
  290.    *(Matthias) 
  291.    */
  292.   static bool canBeRestored(int number);
  293.  
  294.  
  295.   /** Returns the className of the numberth toplevel window which
  296.     * should be restored. This is only usefull if you application uses
  297.     * different kinds of toplevel windows. (Matthias) 
  298.     */
  299.   static const QString classNameOfToplevel(int number);
  300.  
  301.   /** try to restore the specified number. Returns "False" if this
  302.    * fails, otherwise returns "True" and shows the window
  303.    */
  304.   bool restore(int number);
  305.  
  306.   /**
  307.     * Tells the session manager wether the window contains
  308.     * unsaved data which cannot be stored in temporary files
  309.     * during saveYourself. Note that this is somewhat bad style.
  310.     * A really good KDE application should store everything in
  311.     * temporary recover files. Kapplication has some nifty support
  312.     * for that.
  313.     *
  314.     * Default is False == No unsaved data.
  315.     * @see KApplication
  316.     */
  317.   void setUnsavedData( bool );
  318.  
  319.  
  320. protected:
  321.   /** Default implementation calls @ref #updateRects if main widget
  322.      * is resizable. If mainWidget is not resizable it does
  323.      * nothing. You shouldn't need to override this function.  
  324.      */
  325.     virtual void resizeEvent( QResizeEvent *e);
  326.     /**
  327.      * Default implementation just calls repaint (FALSE);
  328.      */
  329.     virtual void focusInEvent ( QFocusEvent *);
  330.     /**
  331.      * Default implementation just calls repaint (FALSE);
  332.      */
  333.     virtual void focusOutEvent ( QFocusEvent *);
  334.  
  335.     /** 
  336.      * The default implementation calls a->accept();
  337.      * Reimplement this function if you want to handle closeEvents.
  338.      * If your window is created on the heap, you may want to do
  339.      * 'delete this;'
  340.      * You must delete any toolbars in your either here or in destructor;
  341.      * The application will quit when this window is closed if you called
  342.      * @ref QApplication::setMainWidget in your main (). You can use
  343.      * memberList - list of all opened KTopLevelWidgets to check if the last
  344.      * window is closed. Or, you can use a signal from Kapplication
  345.      * lastWindowClosed.
  346.      */
  347.     virtual void closeEvent ( QCloseEvent *);
  348.  
  349.     /**
  350.      * DO NOT USE - WILL BE REMOVED
  351.      * returns true;
  352.      */
  353.     virtual bool queryExit();
  354.  
  355.   /** Save your instance-specific properties.
  356.    * You MUST NOT change the group of the kconfig object,
  357.    * since KTW uses one group for each window.
  358.    * Please overload these function in childclasses. 
  359.    *
  360.    * Note that any interaction or X calls are forbidden
  361.    * in these functions!
  362.    *
  363.    * (Matthias)
  364.    */
  365.   virtual void saveProperties(KConfig*){};
  366.   /**
  367.   * Read your instance-specific properties.
  368.   */
  369.   virtual void readProperties(KConfig*){};
  370.  
  371.  
  372.     
  373. protected slots:
  374.     /**
  375.      * Updates child widget geometry. This function is now virtual
  376.      * This is automatically called when the widget is created,
  377.      * new components are added or the widget is resized, or showed.
  378.      * updateRects handles fixed-size and Y-fixed widgets properly.
  379.      *
  380.      * Override it if you intend to manage the children yourself.
  381.      * You normally do not need to do this.
  382.      */
  383.     virtual void updateRects();
  384.  
  385.  private slots:
  386.  /**
  387.    * React on the request of the session manager (Matthias)
  388.    */
  389.     void saveYourself(); 
  390.  
  391.  
  392.  
  393. public:
  394.  
  395.     /**
  396.      * List of members of KTopLevelWidget class
  397.      */
  398.   static QList<KTopLevelWidget>* memberList;
  399.  
  400. private:
  401.     /**
  402.      * List of toolbars.
  403.      */
  404.     QList <KToolBar> toolbars;
  405.  
  406.     /**
  407.      * Main widget. If you want fixed-size or Y-fixed widget just call
  408.      * setFixedSize(w.h) or setFixedWidth (h) on your mainwidget.
  409.      * You should not setFixedSize on KTopLevelWidget.
  410.      */
  411.     QWidget *kmainwidget;
  412.  
  413.     /**
  414.      * Menubar.
  415.      */
  416.     KMenuBar *kmenubar;
  417.  
  418.     /**
  419.      * Statusbar
  420.      */
  421.     KStatusBar *kstatusbar;
  422.  
  423.     /**
  424.      * Frame around main widget
  425.      */
  426.     QFrame *kmainwidgetframe;
  427.  
  428.     /**
  429.      * Stores the width of the view frame
  430.      */
  431.     int borderwidth;
  432.  
  433.   // Matthias
  434. protected:
  435.   void savePropertiesInternal (KConfig*, int);
  436.   bool readPropertiesInternal (KConfig*, int);
  437. };
  438.  
  439.  
  440. #define RESTORE(type) { int n = 1;\
  441.     while (KTopLevelWidget::canBeRestored(n)){\
  442.       (new type)->restore(n);\
  443.       n++;}}
  444.  
  445. #endif
  446.